COMMENT ⊗   VALID 00005 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	\magnification=1200
C00008 00003	{\bf Some \\special Commands}
C00019 00004	{\bf An Example}
C00026 00005	DOVER feature that is not presently on the IMAGEN
C00029 ENDMK
C⊗;
\magnification=1200
\def\TeX{T\kern-.1667em\lower.5ex\hbox{E}\kern-.125em X}
\def\\{$\backslash$}
\parskip 10pt plus 1pt
\parindent 0pt
\pageno=1
\centerline{\bf DVIESP} 
\vskip .1in 
\centerline{\bf Printing DVI files on the Imagen using GF Fonts}
{\bf Introduction}

The DVIESP program converts a DVI file, as generated by TEX82, into an IMP
file using GF files for its font information. The output is then sent to
the Imagen for printing.
This direct use of GF font information may set a
trend but it should be noted that many older but still useful fonts may
not be currently available in GF form.

DVIESP also accepts four {\tt \\special}
commands that are useful in making line drawings involving straight lines,
arcs of circles and segments of ellipses.  The line widths for the various
segments are to be specified in points and the resulting line segments, as actually
printed, will vary in width from 1 to 20 pixels. Drawings, so made, are subject
to any magnification that may be specified for the document. An example of
one such drawing is shown and explained.

The simplest way to invoke the program and to print the entire DVI file
is to type:
\hbox{\tt r dviesp;<dvi file name>}.
This will leave no trace of the IMP file after it has been printed.
Alternatively, one can use the /i switch (see below) to generate an IMP
file without printing it.

{\bf Switches}

The program may be called with switches (one letter per switch):

$$\vbox{\halign{\tt #\hfil\qquad &\vtop{\hsize=26em\strut #\strut}\cr
/f<integer>&The lowest numbered page to be printed will
			be that page in the file whose \TeX\ counter,
			count[0]), has a value equal to that typed.
			The same conventions used by PLAIN \TeX\ to report
			page numbers (negative numbers for Roman)
			are to be used.\cr
\noalign{\medskip}
/n<integer>&This number of pages, in the order of that
			followed by \TeX\ in producing them, will be
			printed starting with the page defined by the
			/f number or starting with the first page
			that \TeX\ processes if no /f value is typed.
			Imagen will, of course, stack the pages in
			the normal order (producing them in reverse).\cr
\noalign{\medskip}
/c<integer>&The indicated number of copies will be printed.
			    This is currently not yet implemented.\cr
\noalign{\medskip}
/i&An IMP file will be generated but not printed. Files, so generated, may
be printed later by using the system command {\tt ESP <imp file name>}.\cr
}}$$
\medskip
Examples:	
\nobreak
$$\vbox{\halign{\tt #\hfil\qquad &#\hfil\cr
r dviesp;foo&Prints the entire file `foo'.\cr
r dviesp;foo/f43&Prints page 43 to the end of the file.\cr
r dviesp;foo/n3&Prints the first 3 pages only.\cr
r dviesp;foo/f6/n3&Prints 3 pages starting with page 6.\cr
r dviesp;foo/f-2/n3&Prints 3 pages starting with page ii.\cr
r dviesp;foo/f67/n1/c3&Prints 3 copies of page number 67.\cr}}$$

If the command line does not contain the name of a DVI file, or if
the given name does not correspond to an accessible file, the program
will initiate a dialog with the user. During this dialog the user
can give the name of the input file and also the spec of the first page
and number of pages to print if they were not given in the command line.
{\bf Some \\special Commands}

DVIESP understands some extended commands that allow \TeX\ to generate line
drawings of any desired degree of complexity, not, however, without some
trouble to the user.
At the present time, the following four special commands are honored with
all arguments expressed in decimal form, the dimensions in points and the
angles in degrees measured from the
positive x axis counterclockwise for positive angles and clockwise for
negatively expressed angles.

{\tt \\special$\{$point <number>$\}$}
\narrower{Remember the current position under the given index number.\smallskip}

{\tt \\special$\{$join <pen size> <number1> <number2> $\ldots$ <numberl>$\}$}
\narrower{Draw straight line segments joining points $\langle$number1$\rangle$ and
$\langle$number2$\rangle$ , $\langle$number2$\rangle$ and
$\langle$number3$\rangle$, $\ldots$, $\langle$ number(l-1)$\rangle$ and
$\langle$numberl$\rangle$.\smallskip}

{\tt \\special$\{$circle <pen size> <radius> <alpha0> <alpha1>$\}$}
\narrower{Draw an arc of a circle between the two specified angles at the
	specified radius.\smallskip}

\hfuzz=2pt
{\tt \\special$\{$ellipse <pen size> <radius0> <radius1> <offset> <alpha0> <alpha1>$\}$}
\narrower{Draw a segment of an ellipse with the two specified radii at an
	axial offset as given and between two points specified by two
	generating angles as given.\smallskip}
\hfuzz=0.1pt

{\bf Straight Line Figures}

Figures composed of straight line segments are drawn by first assigning
numbers to a set of point locations on a page. Points are positioned by
issuing normal \TeX\ commands (\\raise, \\kern, etc) to position \TeX\ to
the desired locations on the page and by giving {\tt \\special$\{$point
<number>$\}$} commands when so positioned. These points can then be joined
by straight line segments using one or more {\tt \\special$\{$joint <pen
size in pts> <number1> <number2> $\ldots$ <number n>$\}$} commands.

For safety, all commands relating to any one figure should be
specifically constrained to be on a single page, for example, by having
them all within a single \\hbox or \\vbox and care should be taken not to
have any unwanted spaces or carriage returns in the command string which
would displace the origin from which the point locations are measured. All
of this will be much easier to understand by referencing the example given
at the end of this report.

While points are remembered across page boundries, no use can be made of
this feature, since DVIESP processs the pages in the reverse order to that
in which they are created by \TeX.  Points, once specified for use on the
same page, may be multiconnected by a series of \\special$\{$join$\}$ commands,
also allowing different pen sizes to be used for the different join
commands.  As many as 256 different points, numbered 0 to 255, may be
specified. Most of the time, this number should be more than
adequate, unless it be to draw an elaborate curved-line figure by
generating a series of very short line segments. Drawings requiring more
than this number of points can always be produced by using a series of
join commands with the point numbers redefined between joins.

The specification of {\tt <pen size>} gives the thickness of the line
segments in points.  Thus
{\tt \\special$\{$join .6 1 2$\}$} joins
points 1 and 2 with a line of width .6pt, or
more precisely $0.6*65536$ DVI units.  If you use \\magnification then of
course everything is enlarged by the magnification factor. The pen sizes
are translated and rounded into pixels and only pixel values of 0 to 20
are allowed. Requested numbers above the upper limit are reduced to 20
automatically. The use of a 0 width pen allows one to define an area that
could be filled with texturing, if and when texturing is implemented.

A pen-drawn line produced by these {\tt \\special} commands should not be
confused with a rectangular rule produced by a {\tt \\hrule} or {\tt
\\vrule} command since the end shape, width and location is defined by the
shape, size and center position of the pen used in its construction.


{\bf Circles and Arcs of Circles}

Circles and arcs of circles are drawn by first issuing normal \TeX\
commands (\\raise, \\kern, etc) to position the center at the desired
locations on the page and then by giving the circle command
\ \ {\tt \\special$\{$circle <pen size> <radius> <alpha0> <alpha1>$\}$}.

The arc is drawn from alpha0 to alpha1 in a counterclockwise direction if
alpha1, as expressed, is numerically larger than than the expressed value
of alpha0, and in a clockwise direction otherwise.  For example, alpha0
might be 15 and alpha1 could be either -15 or 345 to get either the
shorter arc through 0 or the longer arc through 180.  This can be confusing,
but an easy way to check if you are specifying the arc that you desire
(except for
the 180 degree arc case) is to note that the angular length of the arc is
given by the magnitude of the numerical difference between the two
as-expressed angles.

To draw a complete circle, the specified values for the two
angles must differ by 360 degrees.  Giving the same numerical value for
the two angles will produce a pen-sized dot at the specified point.

{\bf Ellipses and Segments of Ellipses.}

Ellipses and segments of ellipses are drawn by first issuing normal \TeX\
commands (\\raise, \\kern, etc) to position the center at the desired
locations on the page and then by giving the ellipse command,
{\tt \\special$\{$ellipse <pen size> <radius0> <radius1> <offset> <alpha0> <alpha1>$\}$}

The two radii, are, respectively, along the x and y axes if the offset is
zero.  The offset angle is measured counterclockwise.
The same rules apply to the
two alphas as noted for the circle case, except that these two angles are
now measured on the circle from which the ellipse is generated and the
actual angles on the resulting ellipse are altered from these values by
the generating process.  While it is possible to do the necessary
translation to allow the specification to be in angles on the ellipse,
these values are usually of limited uses. What one may want are the
coordinates for the two end points and these are more easily computed
from the angles that are given, as may be seen by refering to the 
sketch on page three of this note.

{\bf An Example}

The following example is, perhaps, typical of the kind of figures that can
be drawn. It shows a segment of an ellipse drawn with
an alpha-offset of 30 degrees and with an alpha0 of 30 degrees and an
alpha1 of 180 degrees together with some auxillary circles and lines that
aid in showing the significants of the defining parameters.
The values alpha0 and alpha1 actually apply to the
angles measured on the generating circles.  As shown by the intersecting
constuction lines, the x and y coordinates for the alpha0 point on the
ellipse, as measured in offset coordinates, are given by the x
coordinate for the alpha0 point on the generating circle of radius radius0
and by the y coordinate for the alpha0 point on the generating
circle of radius radius1. 

\smallskip
\newdimen\u  \u=1pt
\def\p(#1,#2)#3{\raise#2\u\rlap{\kern#1\u\special{#3}}}
\def\q(#1,#2)#3{\raise#2\u\rlap{\kern#1\u{#3}}}
\centerline{\hbox {%
	\p(0,43.3){point 1}%
	\p(90,43.3){point 2}%
	\p(90,0){point 3}%
	\p(0,90){point 4}%
	\p(-90,0){point 5}%
	\p(0,-90){point 6}%
	\special{join .482 3 5}% the original x axis
	\special{join .482 4 6}% the original y axis
	\p(86.6,50){point 7}%
	\q(86.6,50){ offset(30)}%
	\p(50,86.6){point 8}%
	\q(50,86.6){ alpha0(30)}%
	\p(-86.6,-50){point 9}%
	\q(-86.6,-50){\llap{alpha1(180)\ }}%
	\p(21.6,37.5){point 10}%
	\p(43.3,75){point 11}%
	\p(58.3,58.4){point 12}%
	\p(55.6,53.2){point 13}%
	\p(0,0){point 0}%
	\special{join .241 0 8}% the sixty degree line
	\special{join .482 7 9}% the shifted axis
	\special{join .241 10 12}% construction line
	\special{join .241 11 13}% construction line
	\special{ellipse 1.45 86.6 43.3 30 30 180}%
 	\special{circle .241 43.3  0 360}%
	\special{circle .241 86.6  0 360}%
	\hfil}}

There are several rather simple ways in which one can go wrong in using
these \\special commands and perhaps it will help to list of the actual
instructions that were use to define this figure. Note particularly, the
use of \\rlap commands in the \\def commands and the use of percent signs
to terminate all lines so that unwanted shifts of the origin are
prevented.

While the pen sizes as specified in this example were chosen at values that
translate rather closely into a fixed number of pixels, this need not be
done and it was actually useless in this use of the sketch since the
diagram was enlarged by the use of a magnification factor for the entire
report.

\def\sign{\null\phantom{a}\lower.25truein
\hbox{{$\scriptstyle\sevensy ALS$} \sevenrm 6-27-85}}
\footline={\ifnum \pageno=5 \lastpage \else \normpage\fi}
\def\lastpage{\phantom{\sign}\hfil \folio \hfil \sign}
\def\normpage{\hfil \folio \hfil}

 The list of instructions follows:
\medskip
\parskip 0pt
\obeylines{\tt \\newdimen\\u  \\u=1pt
\\def\\p(\#1,\#2)\#3$\{$\\raise\#2\\u\\rlap$\{$\\kern\#1\\u\\special$\{$\#3$\}$$\}$$\}$
\\def\\q(\#1,\#2)\#3$\{$\\raise\#2\\u\\rlap$\{$\\kern\#1\\u$\{$\#3$\}$$\}$$\}$
\\centerline$\{$\\hbox $\{$\%
	\\p(0,43.3)$\{$point 1$\}$\%
	\\p(90,43.3)$\{$point 2$\}$\%
	\\p(90,0)$\{$point 3$\}$\%
	\\p(0,90)$\{$point 4$\}$\%
	\\p(-90,0)$\{$point 5$\}$\%
	\\p(0,-90)$\{$point 6$\}$\%
	\\special$\{$join .482 3 5$\}$\% the original x axis
	\\special$\{$join .482 4 6$\}$\% the original y axis
	\\p(86.6,50)$\{$point 7$\}$\%
	\\q(86.6,50)$\{$ offset(30)$\}$\%
	\\p(50,86.6)$\{$point 8$\}$\%
	\\q(50,86.6)$\{$ alpha0(30)$\}$\%
	\\p(-86.6,-50)$\{$point 9$\}$\%
	\\q(-86.6,-50)$\{$\\llap$\{$alpha1(180)\\ $\}\}$\%
	\\p(21.6,37.5)$\{$point 10$\}$\%
	\\p(43.3,75)$\{$point 11$\}$\%
	\\p(58.3,58.4)$\{$point 12$\}$\%
	\\p(55.6,53.2)$\{$point 13$\}$\%
	\\p(0,0)$\{$point 0$\}$\%
	\\special$\{$join .241 0 8$\}$\% the sixty degree line
	\\special$\{$join .482 7 9$\}$\% the shifted axis
	\\special$\{$join .241 10 12$\}$\% construction line
	\\special$\{$join .241 11 13$\}$\% construction line
	\\special$\{$ellipse 1.45 86.6 43.3 30 30 180$\}$\%
 	\\special$\{$circle .241 43.3  0 360$\}$\%
	\\special$\{$circle .241 86.6  0 360$\}$\%
	\\hfil$\}$$\}$}
\vfil\eject\end
DOVER feature that is not presently on the IMAGEN

The following \specials are partially implemented for the DOVER and are
being considered for the IMAGEN. It is thought that they would be of
limited utility and a more powerful set of commands (as permitted by the
IMAGEN) is being considered.  In particular, it would be possible to
define an arbitrary textured pattern and to apply it to any singly
connected region.  The writer (ALS) would be interested in an expression
of interest.

\\special$\{$rectangle $<$number1$>$ $<$character$>$ $<$number2$>$ $<$number3$>$$\}}

	The four low order bits of $<$number1$>$ describe the lower row
	of a 4*4 square bit pattern. The next higher four bits
	describe the third row from the top of that bit pattern.
	The next four bits describe the second row, and the next higher
	order four bits describe the top row. 	The bitmap given in
	this way will be replicated to fill the rectangular area.

	The $<$character$>$ argument to "rectangle" gives the bit-painting
	function that should be used in this operation. (Caution: Only
	the `o' function is currently implemented on the DOVER (see below.)

		0	Clear the rectangle.
		1	Blacken the rectangle (the effect is the
			same as that of a rule of the same dimensions).
		s	Replace the previous contents of the rectangle
			by the new rectangle filled in with the pattern.
		o	Logical ``or'' the new rectangle on the previous
			contents. (Same as overstriking one bitmap
			with the other.)
		x	Logical ``xor'' the new rectangle on the previous contents.
		a	Logical ``and'' the two rectangles.

	$<$number2$>$ and $<$number3$>$ are point indices for two opposite
	corners of the rectangle.

\bye